home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / dev / basic / RIBlitzLibs.lha / riblitzlibs / docs / RIPackLib.doc < prev    next >
Encoding:
Text File  |  1995-01-29  |  6.9 KB  |  160 lines
  1. -----------------------------------------------------------------------------
  2. ====                     RI Pack Library V1.2 (C)1994              ====
  3. -----------------------------------------------------------------------------
  4.  
  5.                 Written By Stephen McNamara & Steven Matty
  6.                         ©1994 Leading Edge Software
  7.  
  8.  
  9. This library contains commands for the unpacking of ILBM's (IFF pictures)
  10. and the grabbing of their palettes (CMAP chunks).  Nearly all the commands
  11. in this library can be used as either STATEMENTS or FUNCTIONS.  Usage is
  12. identical in both cases but if used as a function then the command will
  13. return:
  14.     FALSE for failure
  15.     TRUE for success
  16.  
  17.  
  18. Command list:
  19.       UnpackIFF address.l,bitmap#[,lines,offset]
  20.       suc=UnpackIFF (address.l,bitmap#[,lines,offset])
  21.       ILBMPalette address.l,palette#
  22.       suc=ILBMPalette (address.l,palette#)
  23.       ILBMGrab address.l,bitmap#,palette#
  24.       LoadIFF filename$,bitmap#[,palette#]
  25.       suc=LoadIFF (filename$,bitmap#[,palette#])
  26.       DeIce source_address,dest_address
  27.       suc=DeIce (source_address,dest_address)
  28.       val.l=ChunkHeader (A$)
  29.  
  30. Statement/Function: UnpackIFF
  31. ------------------------------------------------------------------------
  32. Modes : Amiga/Blitz
  33. Syntax: UnpackIFF address.l,bitmap#[,lines,offset]
  34.   suc=UnpackIFF (address.l,bitmap#[,lines,offset])
  35.  
  36.   This command is used to unpack an IFF picture file from memory onto a
  37. bitmap.  Address.l should point to the START of the iff file header in
  38. memory (either CHIP or FAST mem can be used), bitmap should be the number
  39. of a previously initialised bitmap.  The optional lines parameter allows
  40. you to specify the number of lines to unpack from the IFF file.
  41.   This command checks the size of the bitmap against the size of the IFF
  42. before it unpacks the IFF onto it.  Checks are made for width, height and
  43. depth of the bitmap and the IFF and the following is done:
  44.  
  45. (size=WIDTH, HEIGHT and DEPTH)
  46.  
  47.     BITMAP 'size' < IFF 'size' : unpack aborted
  48.     BITMAP 'size' = IFF 'size' : pic is unpacked
  49.     BITMAP 'size' > IFF 'size' : pic is unpacked
  50.  
  51.   Extra aborts can be caused by:
  52.     - not using a previously installed bitmap
  53.     - given the optional lines parameter as 0 or less
  54.     - not giving ADDRESS.l as a pointer to a valid IFF ILBM
  55.       header
  56.  
  57.   When using the optional parameters, you should note that if you try to
  58. unpack more lines than the IFF has, the unpack routine will automatically
  59. stop at the last line of the IFF.  It will not reject the UnpackIFF
  60. command.  Also note that the offset is a byte offset from the start of the
  61. bitplanes.  You can use the AddValue command to calculate this value.
  62.  
  63.   NOTE: you should save your IFF pictures with the STENCIL OFF because at
  64. the moment this routine does not check to see if STENCIL data is present in
  65. the IFF file.
  66.  
  67. Statement/Function: ILBMPalette
  68. ------------------------------------------------------------------------
  69. Modes : Amiga/Blitz
  70. Syntax: ILBMPalette address.l,palette#
  71.   suc=ILBMPalette (address.l,palette#)
  72.  
  73.   This command is used to grab the palette from a IFF picture file held in
  74. memory (CHIP or FAST mem).  Address.l should be given as the address of
  75. either an IFF file in memory or a CMAP chunk in memory.  When you use the
  76. SAVE PALETTE command from inside an art program (e.g. DPaint) or from
  77. inside Blitz2, the program saves out a CMAP chunk which gives details
  78. about the palette.  The CMAP chunk is also saved with IFF picture files to
  79. give the palette of the picture.
  80.   This command will look at the address you gave and try and find a CMAP
  81. chunk from the address given to address+5120.  If it finds a chunk it will
  82. grab the palette into the given palette object.  If the palette object
  83. already contains palette information then this information is deleted.
  84. This routine looks in the CMAP chunk and reserves the palette object to
  85. have the same number of colour entries.
  86.   This command will fail if it doesn't find a CMAP chunk.
  87.  
  88.  
  89. Statement: ILBMGrab
  90. ------------------------------------------------------------------------
  91. Modes : Amiga/Blitz
  92. Syntax: ILBMGrab address.l,bitmap#,palette#
  93.  
  94.   This command lets you grab both the palette and the graphics from an IFF
  95. picture file with just one command.  It returns to success parameter to
  96. say whether or not it succeeded in grabbing the data, so if you need to know
  97. if the grabbing was successful you'll have to use the separate commands
  98. for grabbing palettes and graphics.
  99.  
  100.   NOTE: this command essentially just calls both UnpackIFF and ILBMPalette
  101. so everything said about these commands is relevent for ILBMGrab.
  102.  
  103.  
  104. Statment/Function: LoadIFF
  105. ------------------------------------------------------------------------
  106. Modes : Amiga
  107. Syntax: LoadIFF filename$,bitmap#[,palette#]
  108.   suc=LoadIFF (filename$,bitmap#[,palette#])
  109.  
  110.   This command is a direct replacement for Blitz2's LoadBitmap.  It is a
  111. lot faster than Blitz's command since it loads the file into memory and
  112. then unpacks it from there.  Thus you need to ensure that you have enough
  113. free memory to load the IFF into before trying to use this command.
  114.   This command is also more stable than Blitz's since it checks for the
  115. existence of the file before trying to load it in.
  116.   The optional parameter allows you to load in the palette of the IFF
  117. picture.  Refer to UnpackIFF and ILBMPalette for more information about
  118. unpacking the graphics and grabbing the palettes.
  119.  
  120. IMPORTANT NOTE: to use this command you must have our FUNC library
  121. installed in your copy of Blitz2.  Use of this command without this library
  122. will probably lead to a bad crash of your Amiga!
  123.  
  124.  
  125. Statement/Function: DeIce
  126. ------------------------------------------------------------------------
  127. Modes : Amiga
  128. Syntax: DeIce source_address,dest_address
  129.   suc=DeIce (source_address,dest_address)
  130.  
  131.   This is a command from my (Stephen McNamara) past.
  132.   It is used to unpack data files packed by my favourite Atari ST packer -
  133. PACK ICE v2.40.  I've put it into Blitz because still have loads of files
  134. that I've packed with it.  To use it, source_address should (obviously)
  135. contain the address of the data, dest_address should be where to unpack the
  136. data to.  In the function form, this command returns either 0 for unpack
  137. failed or -1 for success.
  138.   Note: The size of the data unpacked is the long word at source_address+8
  139. (I think, or is it 4?) if anybody is interested......
  140.  
  141.  
  142. Function: ChunkHeader
  143. ------------------------------------------------------------------------
  144. Modes : Amiga
  145. Syntax: val.l=ChunkHeader (A$)
  146.  
  147.   This command was put in by me (Stephen McNamara) before I realised Blitz
  148. already had a command that does exactly the same.  I've left it in just
  149. because I want to.  It is useful when looking through IFF files for chunks
  150. (e.g. ILBM, CMAP, etc.) as it gives you a longword value to look for in
  151. memory to find the chunk.  The string should be a four character string
  152. (e.g. CMAP), you'll be returned the longword value of the string.
  153.   This command does the job of the following bit of Blitz2 code:
  154.  
  155.     a$="CMAP"
  156.     val.l=Peek.l(&a$)
  157.  
  158.  
  159. >> END
  160.